<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
  <head>
    <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
    <title>Hot failover</title>
    <link rel="stylesheet" href="gettingStarted.css" type="text/css" />
    <meta name="generator" content="DocBook XSL Stylesheets V1.73.2" />
    <link rel="start" href="index.html" title="Berkeley DB Programmer's Reference Guide" />
    <link rel="up" href="transapp.html" title="Chapter 12.  Berkeley DB Transactional Data Store Applications" />
    <link rel="prev" href="transapp_recovery.html" title="Recovery procedures" />
    <link rel="next" href="transapp_journal.html" title="Using Recovery on Journaling Filesystems" />
  </head>
  <body>
    <div xmlns="" class="navheader">
      <div class="libver">
        <p>Library Version 12.1.6.2</p>
      </div>
      <table width="100%" summary="Navigation header">
        <tr>
          <th colspan="3" align="center">Hot failover</th>
        </tr>
        <tr>
          <td width="20%" align="left"><a accesskey="p" href="transapp_recovery.html">Prev</a> </td>
          <th width="60%" align="center">Chapter 12.  Berkeley DB Transactional Data Store Applications </th>
          <td width="20%" align="right"> <a accesskey="n" href="transapp_journal.html">Next</a></td>
        </tr>
      </table>
      <hr />
    </div>
    <div class="sect1" lang="en" xml:lang="en">
      <div class="titlepage">
        <div>
          <div>
            <h2 class="title" style="clear: both"><a id="transapp_hotfail"></a>Hot failover</h2>
          </div>
        </div>
      </div>
      <p>
        For some applications, it may be useful to periodically
        snapshot the database environment for use as a hot failover
        should the primary system fail. The following steps can be
        taken to keep a backup environment in close synchrony with an
        active environment. The active environment is entirely
        unaffected by these procedures, and both read and write
        operations are allowed during all steps described here. 
    </p>
      <p> 
        The procedure described here is not compatible with the
        concurrent use of the transactional bulk insert optimization
        (transactions started with the <a href="../api_reference/C/txnbegin.html#txnbegin_DB_TXN_BULK" class="olink">DB_TXN_BULK</a> flag). After the
        bulk optimization is used, the archive must be created again
        from scratch starting with step 1.
    </p>
      <p>
        The <a href="../api_reference/C/db_hotbackup.html" class="olink">db_hotbackup</a> utility is the preferred way to automate
        generating a hot failover system. The first step is to run
        <a href="../api_reference/C/db_hotbackup.html" class="olink">db_hotbackup</a> utility without the <span class="bold"><strong>-u</strong></span>
        flag. This will create hot backup copy of the databases in
        your environment. After that point periodically running the
        <a href="../api_reference/C/db_hotbackup.html" class="olink">db_hotbackup</a> utility with the <span class="bold"><strong>-u</strong></span>
        flag will copy the new log files and run recovery on the
        backup copy to bring it current with the primary environment. 
    </p>
      <p> 
        Note that you can also create your own hot backup solution
        using the <a href="../api_reference/C/envbackup.html" class="olink">DB_ENV-&gt;backup()</a> or <a href="../api_reference/C/envdbbackup.html" class="olink">DB_ENV-&gt;dbbackup()</a> methods. 
    </p>
      <p> 
        To implement your own hot fail over system, the steps below
        can be followed. However, care should be taken on non-UNIX
        based systems when copying the database files to be sure that
        they are either quiescent, or that either the <a href="../api_reference/C/envbackup.html" class="olink">DB_ENV-&gt;backup()</a> or
        <a href="../api_reference/C/db_copy.html" class="olink">db_copy()</a> routine is used to ensure atomic reads of the
        database pages.
    </p>
      <div class="orderedlist">
        <ol type="1">
          <li>
            <p> 
                Run the <a href="../api_reference/C/db_archive.html" class="olink">db_archive</a> utility with the <span class="bold"><strong>-s</strong></span> 
                option in the active environment to
                identify all of the active environment's database
                files, and copy them to the backup directory. 
            </p>
            <p> 
                If the database files are stored in a separate
                directory from the other Berkeley DB files, it will be
                simpler (and much faster!) to copy the directory
                itself instead of the individual files (see
                <a href="../api_reference/C/envadd_data_dir.html" class="olink">DB_ENV-&gt;add_data_dir()</a> for additional information).
            </p>
            <div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">
              <h3 class="title">Note</h3>
              <p>
                    If any of the database files did not have an
                    open <a href="../api_reference/C/db.html" class="olink">DB</a> handle during the lifetime of the
                    current log files, the <a href="../api_reference/C/db_archive.html" class="olink">db_archive</a> utility will not list
                    them in its output. This is another reason it may
                    be simpler to use a separate database file
                    directory and copy the entire directory instead of
                    archiving only the files listed by the
                    <a href="../api_reference/C/db_archive.html" class="olink">db_archive</a> utility.
                </p>
            </div>
          </li>
          <li>
            Remove all existing log files from the backup
            directory.
        </li>
          <li> 
            Run the <a href="../api_reference/C/db_archive.html" class="olink">db_archive</a> utility with the <span class="bold"><strong>-l</strong></span> 
            option in the active environment to
            identify all of the active environment's log files, and
            copy them to the backup directory.
        </li>
          <li>
            Run the <a href="../api_reference/C/db_recover.html" class="olink">db_recover</a> utility with the <span class="bold"><strong>-c</strong></span> option 
            in the backup directory to catastrophically recover the copied environment.
        </li>
        </ol>
      </div>
      <p>
        Steps 2, 3 and 4 may be repeated as often as you like. If
        Step 1 (the initial copy of the database files) is repeated,
        then Steps 2, 3 and 4 <span class="bold"><strong>must</strong></span> be
        performed at least once in order to ensure a consistent
        database environment snapshot. 
    </p>
      <p> 
        These procedures must be integrated with your other
        archival procedures, of course. If you are periodically
        removing log files from your active environment, you must be
        sure to copy them to the backup directory before removing them
        from the active directory. Not copying a log file to the
        backup directory and subsequently running recovery with it
        present may leave the backup snapshot of the environment
        corrupted. A simple way to ensure this never happens is to
        archive the log files in Step 2 as you remove them from the
        backup directory, and move inactive log files from your active
        environment into your backup directory (rather than copying
        them), in Step 3. The following steps describe this procedure
        in more detail: 
    </p>
      <div class="orderedlist">
        <ol type="1">
          <li>
            Run the <a href="../api_reference/C/db_archive.html" class="olink">db_archive</a> utility with the <span class="bold"><strong>-s</strong></span> option
            in the active environment to identify all of the active environment's database files,
            and copy them to the backup directory.
        </li>
          <li> 
            Archive all existing log files from the backup
            directory, moving them to a backup device such as CD-ROM,
            alternate disk, or tape.
        </li>
          <li>
            Run the <a href="../api_reference/C/db_archive.html" class="olink">db_archive</a> utility (without any option) in the
            active environment to identify all of the log files in the
            active environment that are no longer in use, and
            <span class="bold"><strong>move</strong></span> them to the
            backup directory. 
        </li>
          <li> 
            Run the <a href="../api_reference/C/db_archive.html" class="olink">db_archive</a> utility with the <span class="bold"><strong>-l</strong></span> option 
            in the active environment to
            identify all of the remaining log files in the active
            environment, and <span class="bold"><strong>copy</strong></span> the
            log files to the backup directory. 
        </li>
          <li>
            Run the <a href="../api_reference/C/db_recover.html" class="olink">db_recover</a> utility with the <span class="bold"><strong>-c</strong></span> option
            in the backup directory to
            catastrophically recover the copied environment.
        </li>
        </ol>
      </div>
      <p> 
        As before, steps 2, 3, 4 and 5 may be repeated as often as
        you like. If Step 1 (the initial copy of the database files)
        is repeated, then Steps 2 through 5 <span class="bold"><strong>must</strong></span> be 
        performed at least once in order to
        ensure a consistent database environment snapshot.
    </p>
    </div>
    <div class="navfooter">
      <hr />
      <table width="100%" summary="Navigation footer">
        <tr>
          <td width="40%" align="left"><a accesskey="p" href="transapp_recovery.html">Prev</a> </td>
          <td width="20%" align="center">
            <a accesskey="u" href="transapp.html">Up</a>
          </td>
          <td width="40%" align="right"> <a accesskey="n" href="transapp_journal.html">Next</a></td>
        </tr>
        <tr>
          <td width="40%" align="left" valign="top">Recovery procedures </td>
          <td width="20%" align="center">
            <a accesskey="h" href="index.html">Home</a>
          </td>
          <td width="40%" align="right" valign="top"> Using Recovery on Journaling Filesystems</td>
        </tr>
      </table>
    </div>
  </body>
</html>
